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REFERENCES 


A  STANDARD  ORGANIZATION  FOR  SPECIFYING  ABSTRACT 
INTERFACES  FOR  THE  SMMS  APPLICATION 


1.  INTRODUCTION 

There  are  three  major  tasks  in  designing  a  software  system.  The  first  is  partitioning  the  system  into 
work  assignments  (modules).  The  second  is  designing  the  interface  of  each  module,  i.e.,  deciding  what  facili¬ 
ties  the  module  will  provide.  The  third  is  producing  the  specification  for  each  interface  so  that  (a)  the  imple- 
menters  have  enough  information  to  write  the  software;  (b)  writers  of  other  modules  have  enough  informa¬ 
tion  to  use  the  module;  (c)  information  that  constrains  or  discloses  details  of  the  implementation  is  not 
revealed;  (d)  reviewers  can  determine  that  the  specified  module  behavior  is  consistent  with  the  module's 
assigned  security  requirements. 

NRL’s  Secure  N'lilitary  Message  Systems  (SMMS)  project  is  applying  the  NHL  Software  Cost  Redac¬ 
tion  (SCR)  methodology  [SCRSO]  to  the  specification,  design,  and  implementation  of  a  family  of  militaiw' 
message  systems  that  must  meet  demanding  security  requirements.  Information-hiding  [CRITI  and  proof- 
based  decomposition  [SAPj  are  approaches  taken  in  the  first  two  tasks;  abstract  interface  specification  ,ABS 
is  the  approach  taken  for  the  third  task. 

Information-hiding  [CRIT]  is  a  method  of  designing  software  to  reduce  and  make  more  predictable,  the 
impact  (and  hence,  the  cost)  of  making  software  changes.  The  method  involves  dividing  the  software  into 
modules  according  to  likely  changes;  each  module  is  responsible  for  encapsulating  or  “hiding”  the  effects  of  a 
particular  change  from  the  rest  of  the  system.  The  key  is  to  design  the  interface  of  a  module  so  that  it 
reveals  only  information  about  the  module  that  is  not  likely  to  change.  In  that  way.  when  changes  that 
affect  a  module  are  required,  only  the  implementation  of  that  module  is  required  to  be  modified.  The  inter¬ 
face  and  aU  other  modules  that  use  the  interface  are  not  likely  to  change  at  all. 

Such  an  interface  is  called  an  abstract  interface,  because  it  is  an  abstraction  of  what  makes  up 
a  module  in  the  same  way  that  a  road  map  of  the  world  is  an  abstraction  of  the  world.  There  are  many 
things  about  the  world  that  could  change  (e.g.,  the  location  and  number  of  all  the  buildings,  trees,  people, 
etc.),  but  a  user  of  a  road  map  is  not  concerned  with  these  things;  hence,  the  map  does  not  necessarily 
change.  The  specification  of  an  abstract  interface  should  have  the  following  properties: 

•  It  must  not  disclose  any  of  the  changeable  aspects  (“secrets”)  of  the  module. 

•  It  must  present  a  concise  description  of  the  facilities  available  from  the  module,  in  terms  of 
effects  that  are  observable  to  the  user: 

•  It  should  be  divided  into  sections  and  formatted  so  that  a  reader  unfamiliar  with  the  module  is 
able  to  find  a  piece  of  information  without  having  to  study  the  entire  interface  specification;  i.e., 
it  should  serv  the  quick-reference  reader  as  well  as  the  first-time  reader; 

•  It  should  not  duplicate  information,  which  would  make  using  and  maintaining  the  document 
more  difficult. 

The  overall  organization  chosen  to  achieve  these  properties  appears  in  Table  1.  Complete  descriptions  of 
each  section  can  be  found  in  Section  2. 
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This  organization  is  somewhat  different  from  the  SCR  approach,  which  was  geared  to  software  for 
hard  real-time-systems.  Such  systems  typically  have  been  programmed  in  an  assembly  language  rather  than 
a  higher  order  language  and  they  must  often  control  a  variety  of  concurrently  operating  sensors  and  devices 
with  varymr  deadlines.  The  SMMS  application  will  be  programmed  in  higher  order  languages,  and  it  will 
not  generally  have  to  meet  hard  real  time  constraints,  but  it  will  have  to  meet  stringent  security  require¬ 
ments.  Because  of  these  differences  in  applications,  some  parts  of  the  structure  defined  in  SCRSO  are 
unused  here,  and  a  few  new  parts  have  been  added. 

Specifically,  sections  documenting  user  exceptions  and' security  exceptions  have  been  added  to  the  stan¬ 
dard  organization.  The  XRL  SCR  methodolog>'  anticipates  that  a  system  could  operate  even  if  checking  for 
L'ndesired  Event,*  fUEs)  were  turned  off  (perhaps  for  the  sake  of  efficiency).  In  order  to  assure  that  an 
SMMS  family  member  enforces  its  security  requirements,  it  should  be  impossible  for  the  system  to  operate  if 


Introduction 


A  brief  prose  overview  of  the  module's  facilities  to  help  the  reader 
determine  if  this  is  the  module  he  is  interested  in: 


Interface  Overview 


Local  Type  Definitions 
Dictionary 


Undesired  Event  Dictionary 


■A.  table  of  programs  on  the  module's  interface,  showing  tiie  ..."t^rs 
and  parameter  types  and  stating  the  effects  of  each: 

Definitions  of  the  data  types  available  to  users  from  the  module: 

Definitions  of  any  specialized  terms  used  throughout  the 
specification; 

Definitions  of  any  possible  incorrect  uses  by  the  software  of  the 
module's  facilities  or  hardware  errors; 


User  Exception  Dictionary 


Definitions  of  any  possible  incorrect  uses  of  the  module's  facilities 
by  a  human  user  that  result  in  other  than  a  security  violation; 


Security  Exception  Dictionary  Definitions  of  any  possible  incorrect  uses  of  the  module's  facilities 

by  a  human  user  that  can  result  in  a  security  violation: 

System  Generation  Parameters  .A.  list  of  those  quantitative  characteristics  of  the  module  that  are 

not  bound  until  just  before  run-time  (e.g.,  the  size  of  a  data  structure). 


Design  Issues 


Implementation  Notes 


Assumptions  Lists 


A  prose  section  explaining  why  certain  design  decisions  were  made 
to  aid  people  who  might  make  future  changes  to  the  design: 

A  prose  section  to  capture  information  that  might  have  come  to  the 
designer’s  attention  that  would  be  of  use  to  the  implementors: 

A  prose  section  documenting  the  assumptions  that  the  users  of  the 
module  are  allowed  to  make  about  it. 


Unimplemented  Features 


Specifications  of  features  not  provided  in  initial  versions  of  the 
software. 


Efficiency  Guide 


Mapping  to  Requirements 
Facilities  Index 


Specifications  of  the  run-time  resources  consumed  by  using  the 
facilities  on  thv  interface. 

Listing  relating  individual  features  to  individual  requirements. 

.A  quick  look-up  reference  of  all  programs  and  term.*  defined  in  the 
specification  : 


Table  1  —  Organisation  overview 
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the  checking  for  certain  kiniis  of  exceptions  is  disabled.  In  order  to  distinguish  the  members  of  this  class  that 
specifically  concern  security,  the  class  is  subdivided  into  security  and  user  exceptions.  The  existence  of  these 
classes  also  makes  it  easier  for  readers  to  distinguish  conditions  that  represent  potential  security  violations 
from  other  kinds  of  errors. 

A  section  documenting  the  mapping  from  interface  programs  to  the  sv'stem  requirements  and  security 
architecture  has  been  added  to  help  readers  assure  that  each  module  in  the  design  has  a  valid  reason  to  be 
there.  Unused  from  the  earlier  organization  are  the  accuracy  guide,  which  defined  the  tolerances  on  data  pro¬ 
vided  by  sensors,  and  events,  which  permit  specification  of  programs  that  do  not  return  until  a  defined  condi¬ 
tion  holds.  Matching  value/effect  program  pairs  have  been  ieft  unabbreviated  in  the  interface  overview  sec¬ 
tion,  and  enumerated  tjqies  have  been  removed  from  the  local  data  types  section.  That  these  facilities  are 
unused  here  reflects  only  on  the  application  requirements  and  the  current  SMMS  design  approach,  not  on 
their  general  utility.  Future  revisions  to  the  SMMS  design  are  free  to  use  them  as  required. 

2.  DESCRIPTION  OF  TI^E  STANDARD  ORGANIZATION 

The  format  for  specifying  an  abstract  interface  consists  of  the  following  sections: 


2.1  Introduction 

This  section  introduces,  in  informal  prose,  the  features  provided  by  the  module.  It  may  define  basic 
concepts  that  are  used  m  the  rest  of  the  specification. 


2.2  Interface  Overview 

The  interface  overview  section  includes  tables  that  provide  an  overview  of  facilities  provided  by  the 
module.  Readers  familiar  with  the  module  interface  can  use  these  tables  to  refresh  their  memories  about 
particular  facts  without  having  to  reread  the  longer  explanations  in  later  sections.  The  interface  overview 
may  contain  any  of  the  following  subsections: 

Access  Program  Table 

Table  2  shows  the  form  for  the  access  program  table.  This  table  lists  all  access  programs  provided  by 
the  module,  as  well  as  the  number,  data  type,  and  semsmtics  of  the  parameters,  .\ccess  programs  can 
change"  or  retrieve  information  that  is  stored  in  a  module’s  internal  storage.  ,A.ccess  program  names  begin 
and  end  with  brackets  that  show  when  they  can  be  used:  -P-i-  brackets  indicate  programs  that  may  be 
invoked  only  at  system-generation  time:  -f  brackets  enclose  programs  that  are  executable  at  run  time.  The 
access  program  table  contains  an  entry  for  each  access  program  provided  by  the  module;  each  entry'  includes 
the  program  name,  parameter  data,  .and  exceptions  (discussed  more  fully  later)  associated  with  the  program. 

There  are  three  types  of  access  programs.  Each  type  is  characterized  by  the  facilities  offered  to  user 
programs,  the  effects  on  other  access  programs  provided  by  the  module,  the  information  required  to  .specify 
them,  and  the  naming  conventions. 

Value  Programs  —  These  programs  deliver  values  to  user  programs  via  output  parameters  .\  call  to 
a  value  program  has  no  effect  on  subsequent  calls  to  that  program  or  on  any  other  program  of  the  same 
module.  Semantics  of  value  programs  are  given  in  the  dictionary  definition(s)  of  the  term(s)  used  to  denote 
the  output  parameterfs).  Value  program  names  usually  begin  with  "Get"  for  Get  value. 
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Effeci  programs  —  These  programs  enable  user  programs  to  alTect  the  I'uture  operation  ot  the  module 
bv  passing  it  information  or  giving  it  commands.  ElTect  programs  may  affect  the  values  returned  by  subse¬ 
quent  calls  to  value  programs,  may  change  the  values  shown  by  displav'  devices,  or  mav  affect  the  current 
operating  slate  of  the  module.  These  programs  do  not  return  value.s  themselves.  The  description  column  m 
•he  access  program  table  can  be  left  blank  for  these  programs  whenever  the  program  elfects  section  ade- 
quatelv  detines  the  parameter  meanings.  Tlie  names  of  effect  programs  usually  begin  -with  "Set"  for  >ei 
value. 

Hybrid  Programs  —  These  programs  have  cnaractenstics  of  both  value  and  etfect  programs:  the\ 
return  salues  and  aiTect  the  future  operation  of  the  module.  These  programs  will  usually  be  described  both 
jv  parameter-information  entries  in  the  access  program  table  and  descriptions  in  the  effects  section. 

The  "Exceptions"  column  lists  ail  the  f.’ndesired  Events.  User  Exceptions,  and  Security  Exceptions  that 
can  occur  during  execution  of  the  specified  access  program. 

Parameters 

.\Ithough  the  access  program  table  specifies  the  required  data  type  for  each  parameter,  'iiere  may  i)» 
further  requirements  on  ilie  vaiues  provided  as  input  parameters.  These  legality  conditions  le.g.,  asserting 
that  a  particular  parameter  must  be  positive)  are  given  in  this  section.  If  no  restrictions  on  any  input 
parameter's  value  is  necessary,  this  section  is  omitted. 

Effects 

This  section  specifies  the  effects  (semamtics)  of  invoking  a  hybrid  or  effect  access  program.  The  effects 
are  specified  completely  in  terms  of  changes  or  results  that  are  completely  observable  by  using  software  or  by 
a  human  observer.  It  is  basic  to  the  information-hiding  methodology  that  no  information  about  the  imple¬ 
mentation  or  other  hidden  aspects  of  a  module  be  divulged  in  this  section.  Effects  may  be  given  by  specify¬ 
ing  changes  in  the  values  that  will  subsequently  be  returned  by  access  programs,  or  events  that  will  occur  at 
a  later  time.  An  •“xample  of  a  human-observable  effect  is  the  positioning  of  a  symbol  on  a  display.  If  any 
run-iime  undesired  events  are  enabled  or  disabled  as  a  result  of  invoking  the  program,  that  is  also  described 
.nere.  there  are  no  effect  or  hybrid  access  programs  in  the  table,  this  section  is  omitted. 

The  access  program  table  may  be  split  into  subtables  of  access  programs  that  have  enough  in  common 
that  it  is  useful  to  study  them  together.  In  this  case,  the  effects  of  the  access  programs  immediately  follow 
each  iubtable. 

2.3  Local  Data  Types 

For  every  program  parameter,  a  type  is  specified  in  the  interface  overview.  This  section  of  the 
specification  defines  the  data  types  that  are  used  in  communicating  with  the  module.  Ail  such  data  types  are 
described  in  this  .section  except  those  that  are  defined  in  another  module  interface  specification,  in  which  case 
a  reference  to  that  specification  is  to  be  given. 

2.4  Dictionary 

This  section  of  the  specification  defines  terms  that  appear  using  the  !-fterm-r!  and  'Iterm!!  notation  in 
other  sections  of  the  specification. 

An  item  of  the  form  !-t-term-(-!  is  used  in  the  access  program  table  to  name  an  output  parameter  of  a 
program.  The  dictionary  definition  of  such  a  !+term+!.  then,  defines  the  value  returned  by  the  access 
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Proqram 

Parameters 

Description 

Exceptions 

}  1  programl~\ — h  or  ~\-programl-\- 

pi :  type  i;K 
p2ltype2;K 

infol 
info  2 

^^^^namel^Po^!^  or  ^^namel^o  or 
%{namel)%  or  %{namel}% 

pNi:typeNl]K 

info  S' 1 

%%nameM*Po%  or%nameM%  or 
%(^nameM)%  or  %{name.\f]% 

H — \-program2~\ — h  or  ~\-program2~\~ 

pi:  typei;K 
p2:  type2;K 

infol 

info2 

pNS:typeN2;K 

infoN2 

H — [~programG  i  f  or  ~\~programG~{~ 

plltypel^K 

p2:type2;K 

infol 
info  2 

ptdJltypeNG’fK 

infoNG 

- Effects - 

++P  rogTaTnI~\ — H  or  ~\~programI~\~  formal  or  informal  description  of  externally  observable  results  of 

invoking  program 

Table  2  —  Access  program  table  format 
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Legend  for  Table  2 


Bold-facf'd 

G 

programJ 

NJ 

pL 

typeL 

K 

infoL 

M 

nameE 


.'vmhols  art*  required.  Other  names  and  letters  are  defined  as  follows: 

number  of  programs  in  the  group,  where  group  is  defined  as  a  set  of  programs 
with  the  same  entries  in  the  exceptions  column,  different  groups  are  separated  by 
a  horizontal  line  in  the  table. 

name  of  the  Jih  program  in  the  group,  where  ,1  =  1 . Ci  if  the  name  contain' 

e  brackets,  that  prograni  may  only  he  invoked  at  system-generation  time;  that 
IS,  that  program  will  exist  only  in  the  support  software  prior  to  the  time  the 
software  is  loaded  onto  the  target  machine  .-V  name  with  -t-  brackets  may  !>e  in¬ 
voked  at  run-time;  that  is.  that  program  will  be  available  for  invocation  on  the 
target  machine. 

number  of  parameters  for  the  .fth  program.  If  zero,  the  parameter  column  is 
empty  for  the  program. 

the  Lth  parameter  of  a  program,  where  L  =  1..  .NJ 

type  of  parameter  pL;  the  name  of  a  data  type  provided  either  by  this  module  or 
another.  If  provided  by  thi.s  module,  it  will  be  defined  in  the  Local  Dat.a  Types 
section  of  the  specification.  If  not  provided  by  the  module,  it  will  be  defined  in 
the  module  corresponding  to  the  module  prefix  provided  in  its  name. 

I.  O.  10  for  input,  output,  and  input-output  parameter  Programs  receive  the 
values  of  input  parameters  and  deliver  the  values  of  output  parameters.  Input- 
output  parameters  serve  both  purposes. 

definition  of  the  meaning  of  parameter  pL;  may  be  ,an  entry  in  the  specification's 
dictionary  (!-eentry  L-e!)  or  an  expression  involving  other  parameters,  such  as  pi 
4-  p2;  infoL  may  be  omitted  for  any  parameter  whose  meaning  is  given  in  the 
effects  section,  or  it  may  be  an  informal  description  summarizing  the  program 
effect  description. 

number  of  exception  dictionary  entries  defined  for  the  group 

Entry*  E  in  the  specif  tetion’s  exception  dictionary,  where  E  =  1,2,  ...M;  the  dic¬ 
tionary  entry  defines  the  circumstances  that  cause  a  program  call  to  be  an  excep¬ 
tion  If  the  name  contains  EcEc  brackets,  the  exception  will  be  detected  before 
run-time,  and  the  u-'er  may  nor  provide  a  run-time  program  to  handle  the  excep¬ 
tion.  If  the  name  has  %  brackets  (with  or  without  the  parentheses  or  braces|, 
the  exception  may  not  be  detected  until  run-time,  and  the  user  is  obligated  to 
provide  a  run-time  exception-handling  program  for  it.  Naturally,  sytstem- 
generation-time  programs  can  only  have  sy.stem-generation-time  LTis  associated 
with  them.  There  are  three  classes  of  exceptions:  Undesired  Events.  Security  Ex¬ 
ceptions,  and  User  Exceptions  (See  sections  2.5,  2.G,  and  2.7  for  mor**  details) 
Undesired  Events  are  denoted  bv  Ec  or  brackets  alone  Secuiity  Exceptions 
and  User  Exceptions  are  surrounded  by  %{  and  )%. 
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program  via  jtput  parameter.  This  gives  llie  seniaiitics  of  the  program  .V'  in  I'rogram  elfeet.s,  th^ 

definition  is  a  only  in  terms  that  can  be  tested  by  the  software  or  a  human  user 

A  "term!'  may  be  used  anyw  here  in  the  specificaiion  (except  to  describe  an  output  parameter  of  a  pro 
^ram)  to  take  the  place  of  a  specialized  technical  definition  that  would  other^vise  liave  to  lie  repe.ued 

The  definitions  may  be  in  either  prose  or  a  formal  notation,  given  m  alphabetical  order  bv  term. 

2.5  Undesired  Event  Dictionary 

.An  iindesired  event  (UE)  i.s  an  exception  resulting  from  a  hardware  or  .software  i-rror  that,  once 
detected,  may  be  handled  by  a  "trap"  that  will  effect  recovery  from  the  error,  h’or  a  more  complete  di.sru.<- 
..;ion  of  UEs  see  ITl  . 

.A  LTl  occurs  when  an  assumption  about  an  undesired  event  is  violated,  usually  when  an  access  pro¬ 
gram  IS  called  with  an  incorrect  parameter  or  m  a  state  m  which  it  cannot  be  executed  succes'-fully  This 
section  defines  the  conditions  that  correspond  to  each  undesired  event  repor'ed  by  the  module. 

.A  IE  IS  considered  enabled  when  the  LT.  may  occur  and  inhibited  when  it  is  impossible  for  it  to 
cxrcur.  Some  L'E.s  are  always  enabled.  Some  LTis  are  inhibited  or  enabled  by  access  programs  (user- 
controlled  state  L'Es).  Some  LTis  are  inhibited  or  enabled  by  changes  detected  within  the  module  (internal 
state  L'Es),  and  their  status  is  available  via  access  programs.  If  some  assurance  can  be  given  liiat  a  ITT  will 
never  occur,  it  is  permissible  to  remove  its  detection  code  from  a  production  version  of  the  system  to 
improve  performsmce. 

This  section  defines  the  ‘-'cterm'^  or  '^Ecterm'fc’Ec  entries  in  the  access  program  table  by  stating  the 
violation  that  each  one  represents.  .A  of  the  form  EcEcterm'^Ec  will  be  detected  at  system  generation 
time  .A  EE  of  the  form  '^termEc  may  not  be  detected  until  run  lime.  The  specification  describes  ii.ser- 
controlled  state  L'Es  in  terms  of  the  commands  that  inhibit  or  enable  them  and  internal  state  LEs  in  term.' 
of  the  value  programs  that  reveal  w  liether  the  L'E  is  '■urrently  inhibited  or  enabled. 

2.8  User  Exception  Dictionary 

.A  user  exception  occurs  when  i  ■'ondiiion  motivated  by  functional  reiimreineni,-'  (outside  the  securitv 
model  constraints)  is  violated.  It  results  from  an  action  on  a  human  user's  part  rather  tlian  an  error  in  the 
calling  program.  Programs  that  use  the  module  may  <lepend  on  it  for  detection  and  reporting  of  user  excep¬ 
tions.  This  section  defines  the  conditions  that  correspond  to  eacn  user  exception  reported  bv  the  module 
The  access  program  is  required  to  detect  and  report  each  user  exception  when  it  occurs;  therefore,  a  user 
exception  is  always  enabled 

This  section  defines  the  Ec(term)En  entries  in  the  access  program  table  by  slating  the  violation  that 
each  one  represents.  .A  user  exception  can  not  be  detected  until  run  lime. 


2.7  Security  Exception  Dictionary 

.A  security  exception  occurs  when  a  condition  mc:..aied  by  security  model  .-onstraint,-  i.s  violated.  It 
results  from  an  action  on  a  human  user's  part  rather  than  an  error  m  the  calling  program.  Programs  that 
use  the  module  may  depend  on  it  for  the  detection  and  reporting  of  such  exceptions.  This  section  defines  the 
conditions  that  correspond  to  each  security  exception  reported  by  the  module.  The  .icces.s  program  is 
required  to  detect  and  report  each  security  exception  when  it  occurs;  therefore,  a  security  exception  is  always 
enabled. 
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This  section  detines  the  ‘Tdtermt'T-  entries  in  the  access  program  talde  by  stating  the  violation  lliat 
each  one  represents.  A  security  exception  can  not  be  d.etected  until  run  tune 

2.8  System  Generation  Parameters 

This  section  describes  those  externally  visible  characteristics  of  the  module  that  can  be  ■  haiigeii  b\ 
assigning  values  to  parameters  at  system  generation  time.  Each  parameter  is  named,  ns  data  r>pe  is 
and  its  meaning  is  described.  These  parameters  are  denoted  by  ^term#.  and  may  be  used  as  symbolic  con¬ 
stants  by  users  of  the  module. 


2.9  Interface  Design  Issues 

This  prose  section  describes  any  alternative  designs  that  were  con.sidered  and  records  the  rea.'^n  for 
their  rejection.  The  section  serves  as  a  history  of  design  decisions,  so  that  issues  are  not  considered  rejieat- 
edly  It  serves  as  a  design  rationale  providing  guidance  tc  maintenance  programmers  revi.'^ing  the  program 

2.10  Implementation  Notes 

This  prose  section  contains  implementation  notes.  During  the  design  of  the  module  mierface,  cf‘rt.ain 
facts  or  ideas  may  come  to  the  designer's  attention,  ideas  that  would  be  necessary  or  useful  to  future  imple- 
nienters,  and  these  are  noted  in  this  section. 


2.11  Assumptions  Lists 

The  information  in  the  assumptions  lists  may  be  redundant.  It  is  implied  by  the  description  of  the 
facilities  specihed  in  the  rest  of  the  section.  The  purpose  of  the  assumptic  n  list  is  to  serve  :is  .an  explicit 
medium  for  review  by  nonprogrammers.  Supplying  this  list  for  the  benefit  of  rionprogrammers  iiece.ssitate.'; 
the  redundancy. 

This  section  comprises  four  prose  subsections. 

Baste  Assumptions 

These  assumptions  contain  information  that  users  of  the  module  may  assume  will  never  change.  In  the 
case  of  hardware-hiding  modules  MGi.  it  consists  of  information  that  will  remain  true  about  the  interface 
even  if  the  hidden  hardware  is  replaced  or  modified.  In  the  case  of  requirements-hiding  modules,  it  consists 
of  information  that  will  remain  true  even  if  the  iiidden  requirements  are  changed.  In  rhe  case  of  software 
decision-hiding  modules,  it  consists  of  information  that  will  remain  true  even  if  the  hidden  sofiware  decisions 
are  changed. 

The  assumptions  relate  to  the  normal  use  and  operation  of  the  module  .A  basic  .assumption  will  fall 
into  one  of  two  categories:  implementability  (an  assumption  that  the  module's  facilities  can  be  implemented 
efficiently),  and  sufficiency  (an  assumption  that  the  given  facilities  are  all  the  user  will  ever  need) 
Specifically,  they  may  concern:  (a)  information  available  from  the  module;  fb)  information  that  must  be  su[v 
plied  to  the  module;  (c)  tasks  that  can  be  performed  by  the  module;  (d)  operating  states  of  the  module  ,aiid 
how  they  affect  the  information  available  and  the  information  required;  or  (e)  failure  states  of  the  module 
and  how  they  affect  the  information  available. 


Assumptions  About  i'ndesired  Events 


Thb  section  Ibts  assumptions  describing  incorrect  usage  of  the  module  at  run-time.  Violation  of 
each  assumption  is  associated  with  a  run-time  undesired  event.  The  development  version  of  the  system  will 
be  designed  report  the  undesired  event  whenever  a  violation  occurs.  In  the  production  version  of  the  system, 
the  undesired  event-handling  code  will  be  removed,  and  violations  of  the  assumptions  in  this  section  will 
result  in  unpredictable  behavior. 


Assumptions  About  User  Exceptions 

This  section  lists  assumptions  describing  the  functional  usage  of  the  module  at  run-time  (that  are  not 
security-related).  The  system  will  be  designed  to  repiort  the  user  exception  whenever  a  violation  occurs. 

Assumptions  About  Security  Exceptions 

This  section  lists  assumptions  describing  the  functional  usage  of  the  module  at  run-time  that  are 
security-related.  The  system  will  be  designed  to  report  the  security  exception  whenever  a  violation  occurs. 


2.12  Unimplemented  Features 

It  is  often  the  case  that  a  particular  version  of  the  system  may  not  need  features  of  a  module  that  are 
likely  to  be  needed  in  other  versions.  The  interface  descriptions  specify  all  the  features  of  a  module,  but  in 
this  section  those  features  that  will  not  be  available  in  the  initial  version  are  identified.  The  programmer 
can  use  this  information  about  likely  future  additions  to  design  his  software  for  easier  extension. 

For  each  unimplemented  feature,  an  undesired  event  is  specified  (in  the  access  program  table)  that  will 
be  raised  if  a  programmer  attempts  to  use  the  feature. 

2.13  Efficiency  Guide 

This  section  contains  specifications  of  the  run-time  resources  (memory',  cpu  time)  consumed  by  invok¬ 
ing  the  access  programs  on  the  module’s  interface.  If  precise  measures  are  not  available,  then  guidelines  for 
more  efficient  usage  will  be  given.  This,  of  course,  may  be  implementation  dependent. 


2.14  Mapping  to  Requirements 

This  section  contains  a  mapping  between  the  interface  programs  and  the  system  requirements  'REQ! 
to  which  they  can  be  traced.  In  instances  where  the  interface  programs  do  not  map  directly  to  the  system 
requirements,  a  .:tacem«.iit  of  how  the  interface  programs  map  indirectly  to  the  requirements  must  be 
given. 


2.15  Facilitk  -..dex 

.Alter  all  the  submodules  in  the  document  have  been  specified  using  the  foregoing  scheme,  an  index  is 
provided  that  shows  where  in  the  document  a  particular  name  is  defined.  The  index  includes  a  list  of  access 
programs,  local  data  types,  dictionary  items,  undesired  event  and  exception  names,  and  system  generation 
parameters.  The  system  generation  parameter  list  includes  a  range  of  expected  values  for  each  parameter. 
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2.16  References 


.\iiy  other  documents  to  which  a  reference  is  made  shall  be  defined  here. 


3.  NOTATION  CONVENTIONS 

Table  3  lists  the  notational  brackets  used  and  indicates  what  section(s)  of  an  interface  specification 
gives  relevant  information. 

Notation_ Meaning_ Where  to  Look  It  Up 


-f- i-name-p-f- 

A  module  access  program  that  may  only 
be  invoked  at  system  generation  time 

Section  2 

-(-name-(- 

A  module  access  program  that  may  be 
invoked  at  run-time 

Section  2 

-rGetName-P  or 
-r-t-GetName-p- p 

A  value  access  program:  does  not  change 
the  state  of  the  module,  but  returns  a 
value  described  in  the  dictionary 

Sections  2.5 

-pSetName-P  or 
-P-pSetName-p-i- 

An  effect  access  program:  changes  the 
module  state  as  described  m  Section  2 

Usually  returns  no  value. 

Section  2 

%9oname%% 

An  undesired  event  that  will  be  detected 
at  system-generation  time 

Sections  2.5 

%na.me% 

An  undesired  event  that  may  not  be 
detected  until  run-time 

Sections  2.5 

A  user  exception 

Sections  2,S 

9o{name}% 

A  security  exception 

Sections  2.7 

!-Pname-p! 

The  name  of  a  value  produced  by 
a  module’s  access  program:  its 
definition  is  given  in  the  specification's 
dictionary  section. 

Sections  2. -4 

!!name!! 

Used  to  denote  a  term  with  a  specialized 
definition  that  appears  frequently  in  the 
specification;  its  definition  is  given  in 
the  specification’s  dictionary  section. 

Section  4 

#name# 

The  name  of  a  system-generation  time  Section  6 

parameter 

Table  3  —  Notation  Convention  Table 

The  names  of  all  access  programs,  local  types,  dictionary  terms,  exceptions,  and  system  generation 
parameters  referenced  from  other  modules  shall  be  prefixed  by  the  identifier  of  the  second-level  module  in 
which  the  name  is  defined,  followed  by  a  period.  This  will  result  in  names  of  the  form  X.name.  which  shall 
be  defined  in  the  relevant  section  of  reference  [Xl.  For  example,  the  definition  of  !!SP. classification!!  can  be 
found  by  looking  it  up  in  the  Security  Policy  Interface,  |SPf 
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4.  EX.\MPLE 


The  following  i#  an  example  to  illustrate  the  form  of  tlie  first  eight  sections  of  a  specification  of  an 
abstract  interface.  (The  remaining  sections  of  the  specification,  composed  of  an  index  and  prose  paragraphs, 
are  not  shown. i  It  has  been  taken  from  Chapter  Two  of  the  "Interface  Specifications  for  the  Entity  Monitor 
Module".  The  interface  specification  SP  will  provide  additional  examples. 


User  Primitives  Module 


1.1.1.  Introduction 

This  module  provides  facilities  to  authorize  new  users  and  associate  tliem  them  witli  userlD's, 
'!clearance!!s  and  specific  rights. 


1.1.2.  Interface  Overview 


1.1. 2.1.  ACCESS  PROGRAM  TABLE  -  User  Functions 


Program 

Parameters 

Description 

Excevtions 

e-CreaieUser-r 

pi;  .-VEM  name;  I 

■fuser  name'.! 

'''f(user  name  takenj'T 
Tcjuser  not  sso}‘T' 

-Destroy  L'ser-e 

pi:  userlD;  I 

!!user  identifier!! 

‘Tfno  such  user  pllCr 
'Tiuser  not  .ssofM: 

—ExistsUser-f 

pi.  userlD;  I 

p2:  .ABM.  boolean;  0 

!!user  identifier!! 

!-rUser  exists+! 

‘^fno  such  user  pi  I'T 

-i-ExistsUserName4- 

pi:  .ABM. name:  I 
p2;  .ABM. boolean:  0 

potential  !!user  name!! 
’a-user  name  exists+! 

none 

+GetCurrentL'ser+ 

pi:  userlD;  0 

!+current  user+! 

none 

-t-GetUserDD— 

pi:  .ABM. name;  I 
p2:  userlD:  0 

"user  name!! 

"user  identifier!! 

'^'c(no  such  user  name  [ 

-f-GetL’ser.\'ame->- 

pi:  userlD;  I 
p2:  .ABM. name;  0 

!!user  identifier!! 

"user  name!! 

'T(no  such  u.'or  pi  )M 

-eComparePassword+ 

pi:  userlD:  I 
p2:  .ABM.string:  I 

"user  identifier!! 
Ifpaiisword!! 
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+SetPassword+ 


+GetUserClearance+ 


+SetUserClearance+ 


+GetCurrentTerminal+ 


+GetDefaultPrinter+ 


+SetDefau]tPriiiter+ 


+CreateUser+ 


+DestroyUser+ 


+SetPassword+ 


+SetUserClearance+ 


p3;  .\BM. boolean;  O 


pi:  userED;  I 
p2;  .\BM. siring;  I 


pi:  userED:  I 

p2:  .\B\I.securityLev;  O 

pi:  userlD;  I 

p2;  .\BM.securityLev;  I 

pi:  .\BM. cardinal;  I 
pi:  cardinal:  I 

pi:  ent;  I 


!+user  authenticated+l 


lluser  identifier!! 
Ilpassword!! 


lluser  identifier!! 
l+user  clearance+! 

lluser  identifier!! 
■Iclearancel! 


IIICL  parameter  position!! 
IIICL  parameter  position!! 
Ildefault  printer!! 


•^(no  such  user  pl)^ 
‘^{not  the  current  user  or 
sso}Pc 


“^(no  such  user  pl)'^ 
Pp{not  the  current  user  or 
sso}*^ 


‘^(no  such  user  pl)Pc 


‘^(no  such  user  pl)'^ 
'?b{user  not  ssop'c 

9onot  logged  inTc 

^(printer  not  set)*^ 

?onot  a  device‘s 
'^(no  such  entity  pi 


- Effects - 

+ExistsUserName+(  pi  )’  =  true 
+ExistsUser+(  +GetUserID+(  pi  )  )’  =  true 
+GetUserClearance+(  +GetUserID+(  pi  )  )’  =  $SystemLow$ 
r  .  +IiiAuthRole+(  +GetUserID+(  pi  ),  r)’  =  false 
r.+InRole+{+GetUserED-(-(  pi  ),  r)’  =  false 
(+GetUserName+(  +GetUserID+(  pi  )  ))’  =  pi 
+ExistsUser+(pl)’  =  false 

+ExistsUserName+{  +GetUserName-r(pl)isj  )is",  =  false 
+ComparePassrword+(pl,p2)’  =  true 
i.  i5^p2.  +ComparePassword+(pl.i)’  =  false 
+GetUserClearance-(-(pl)’  =  p2 
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+GetCurrentTerminal+  +ArgEnt+(pl)’  =  !!current  terminal!! 
-rGetDefauhPrinter+  +.\rgEnt+(pl)’  =  !!default  printer!! 
-i-SetDefaultPrinter+  +GetDefaultPrinter+(+CurrentUser4-  S|)!s'  =  pi 


1.1.3.  Local  type  definitions 

userlD  The  internal  representation  of  a  !!user  identifier!!. 

1.1.4.  Dictionary 

!!clearance!!  A  !!security  level!!  denoting  the  level  of  trust  associated  with  a  user. 

!!correct  password!!  !!password!!  associated  with  a  !!user  identifier!!.  When  the  system  is  initialised 

the  resulting  system  state  determines  what  !!user  identifier's  and  !!password!!s  are 
considered  correct  for  what  user  identifiers.  After  initialization  the  correct  pass¬ 
word  is  the  password  most  recently  associated  with  that  user  by  -hSetPassword-h  or 
the  initial  setting  if  no  subsequent  calls  to  -i-SetPassword-l-  have  been  made. 

!!current  terminal!!  The  handle  to  the  !!device!!  that  the  !!current  user!!  is  logged  in  on.  .•Vny  user 
actions  sensed  by  this  !!device!!  are  assumed  to  be  originated  by  the  !!current  user!!. 

'.'current  user.''  The  user  on  whose  behalf  the  client  program  making  the  call  is  running. 

!-)-current  user-i-!  Holds  a  !!user  identifier!!  indicating  the  !!current  user!!. 

!!default  printer!!  A  !!device!!  that  has  been  set  aside  for  the  ;!current  user!!  to  use  as  a  printer. 

!!password!!  A  string  used  to  authenticate  the  user.  Presentation  of  a  !!correct  pass^vord!!  for  a 

particular  !!user  identifier!!  is  considered  sufficient  evidence  that  the  presenter  is 
the  person  denoted  by  that  identifier. 

!-l-user  auihenticated-t-!  True  if  the  !!password!!  presented  is  the  !!correct  password!!  for  the  !!user 
identifier!!.  False  if  no  password  is  associated  with  the  given  !!user  identifier!!  or 
the  passwords  presented  is  not  the  !!correct  password!!. 

!-(-user  ciearance-(-!  The  !!clearance!!  stored  in  the  system  for  the  given  !!user  identifier!!. 

!-(-user  exists-)-!  True  if  and  only  if  the  given  !!user  identifier!!  has  been  successfully  created  by  a 

-t-CreateUser-P  command  and  has  not  been  destroyed  by  a  subsequent  -l-Des- 
troyUser-f  command. 

!!user  identifier!!  An  internally  generated  token  that  uniquely  identifies  a  human  user  on  the  system. 

!!user  name!!  A  string  that  uniquely  identifies  a  human  user  of  the  system. 

!-)-user  name  exists-p!  True  if  and  only  if  the  given  !!user  name!!  corresponds  to  an  existing  !!user 
identifier!!. 
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1.1.5.  Undesired  Event  dictionary 

‘^not  logged  in^  The  llcurrent  user!!  is  undefined;  i.e.,  not  logged  in. 


1.1.6.  User  Exception  dictionary 

%{no  such  user  pl)% 

%{no  such  user  p2)%  The  identifier  given  for  the  !!user  identifier!!  does  not  refer  to  any  defined  user. 

NOT  +ExistsUser+{  x  ) 

where  "x"  is  replaced  by  "pi"  or  "p2". 

%{no  such  user  name  pl)% 

The  string  given  as  a  !!user  name!!  is  unknown  to  the  system. 

NOT  +ExistsUserName+(  pi  ) 

%(prmter  not  sei)%  No  value  for  the  !!default  printer!!  has  been  previously  set. 

'%(user  name  taken)%  The  given  !!user  name!!  is  already  associated  with  a  defined  !!user  identifier!!. 

+ExistsUser+(  +GetUserID+(pl)  ) 


1.1.7.  Security  Exception  dictionary 

%{not  the  current  user  or  sso}% 

An  attempt  was  made  to  perform  an  operation  that  may  only  be  done  by  the  ‘Sys¬ 
tem  Security  Officer’  or  for  the  userlD  that  matches  that  of  the  !!current  user!!. 

NOT  (  +GetCurrentUser-t-  =  pi  )  ANT)  NOT  (  -(-InRole-(-( 

-t-GetCurrentUser-f-,"sso" ) ) 

%{user  not  sso}%  The  !!current  user!!  is  attempting  to  perform  an  operation  that  may  only  be  done 

by  the  ‘System  Security  Officer’,  and  it  is  not  among  his  !!active  roles!!. 

1.1.8.  System  Generation  Parameters  none 
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